theForger's Windows API Programming Tutorial

A guide to getting started in Win32 API Programming

By theForger. Comments/Suggestions appreciated. This is a large page, please be patient while it loads.

• 1. Basics
  • 1.1. Introduction
  • 1.2. Getting started
  • 1.3. Yes, that's all great, but how do I make a window?
  • 1.4. We look for things... Things that make us go.
  • 1.5. Being resourceful.
  • 1.6. Message, Message, Message, Message...
  • 1.7. Your menu sir...
  • 1.8. Dialogs: GUI programmers best friend.
  • 1.9. Old dialog, new tricks.
  • 1.10. Being in Control of the situation.
• 2. Intermediate
  • 2.1. Introduction
  • 2.2. Controls on the Fly
  • 2.3. Things we have in Common
  • 2.4. Reading and Writing Files
  • 2.5. Pretty pictures
  • 2.6. It LIIIIIIVVVESS!!!
  • 2.7. MDI: Please sir, can I have some more?
  • 2.8. Tool and Status Bars

1. Basics

1.1. Introduction

I will format the code to my own style, probably making small changes for clearity. Also the code will be(when possible) adjusted to fit on a standard dos or terminal screen that is 80 characters wide.

I've added complete examples as zip files to most sections. These may not be identical to the ones presented in the document but they'll be pretty close.

1.2. Getting started

#include <windows.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
   LPSTR lpCmdLine, int nCmdShow)
{
   MessageBox(NULL, "Goodbye, cruel world!", "Note", MB_OK | MB_SYSTEMMODAL);
   return 0;
}

If that doesn't work, your first step is to read whatever errors you get and if you don't understand them, look them up in the help or whatever documents accompany your compiler. Make sure you have specified a Win32 GUI(not console) project/makefile/target whatever applies to your compiler. Unfortunately I can't help much with this part either, as errors and how to fix them vary from compiler to compiler (and person to person).

You'll probably get some warnings about you not using the parameters supplied to WinMain(). This is OK. Now that we've established you can in fact compile a program, lets go through that little bit of code....

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
   LPSTR lpCmdLine, int nCmdShow)

HINSTANCE hInstance

Handle to the programs executable module (the .exe file in memory)

HINSTANCE hPrevInstance

Always NULL for Win32 programs.

LPSTR lpCmdLine

The command line arguments as a single string. NOT including the program name. (LPSTR == char*)

int nCmdShow

An integer value which may be passed to ShowWindow(). We'll get to his later.

As of this writing hInstance is always the same with a value of 0x00400000. This fact should not be used in regular programming as this will make portability and possible future changes to break your code. This value is used for things like loading resources and any other task which is performed on a per-module basis.

hPrevInstance used to be the handle to the previously run instance of your program (if any) in Win16. This no longer applies.

WINAPI specifies the calling convention and is currently defined as _stdcall. You will find that many of the normal keywords or types have windows specific definitions, UINT for unsigned int, LPSTR for char* etc... This is theoretically intended to improve portability (across windows platforms that is). Which you choose is really up to you. If you are more comfortable using char* instead of LPSTR, feel free to do so. The only time it really becomes an issue is when writing code to compile on more than one windows platform, (Win16, Win95/98, NT+UNICODE, etc...)

1.3. Yes, that's all great, but how do I make a window?

Download simple_window.zip

I always liked to do things first and learn them later...so here is the code to a simple window which will be explained shortly.

#include <windows.h>

static char g_szClassName[] = "MyWindowClass";
static HINSTANCE g_hInst = NULL;

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   switch(Message)
   {
      case WM_CLOSE:
         DestroyWindow(hwnd);
      break;
      case WM_DESTROY:
         PostQuitMessage(0);
      break;
      default:
         return DefWindowProc(hwnd, Message, wParam, lParam);
   }
   return 0;
}

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
   LPSTR lpCmdLine, int nCmdShow)
{
   WNDCLASSEX WndClass;
   HWND hwnd;
   MSG Msg;

   g_hInst = hInstance;

   WndClass.cbSize        = sizeof(WNDCLASSEX);
   WndClass.style         = NULL;
   WndClass.lpfnWndProc   = WndProc;
   WndClass.cbClsExtra    = 0;
   WndClass.cbWndExtra    = 0;
   WndClass.hInstance     = g_hInst;
   WndClass.hIcon         = LoadIcon(NULL, IDI_APPLICATION);
   WndClass.hCursor       = LoadCursor(NULL, IDC_ARROW);
   WndClass.hbrBackground = (HBRUSH)(COLOR_WINDOW+1);
   WndClass.lpszMenuName  = NULL;
   WndClass.lpszClassName = g_szClassName;
   WndClass.hIconSm       = LoadIcon(NULL, IDI_APPLICATION);

   if(!RegisterClassEx(&WndClass))
   {
      MessageBox(0, "Window Registration Failed!", "Error!",
         MB_ICONEXCLAMATION | MB_OK | MB_SYSTEMMODAL);
      return 0;
   }

   hwnd = CreateWindowEx(
      WS_EX_CLIENTEDGE,
      g_szClassName,
      "The title of my window",
      WS_OVERLAPPEDWINDOW,
      CW_USEDEFAULT, CW_USEDEFAULT, 320, 240,
      NULL, NULL, g_hInst, NULL);

   if(hwnd == NULL)
   {
      MessageBox(0, "Window Creation Failed!", "Error!",
         MB_ICONEXCLAMATION | MB_OK | MB_SYSTEMMODAL);
      return 0;
   }

   ShowWindow(hwnd, nCmdShow);
   UpdateWindow(hwnd);

   while(GetMessage(&Msg, NULL, 0, 0))
   {
      TranslateMessage(&Msg);
      DispatchMessage(&Msg);
   }
   return Msg.wParam;
}

static char g_szClassName[] = "MyWindowClass";
static HINSTANCE g_hInst = NULL;

The second provides a storage spot for the hInstance parameter we get in WinMain().

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)

Windows programs, unlike DOS programs, are event or message driven. This means that in general they sit idle and do nothing untill they receive a message, they act on the message, and then wait around for the next one. This is different than DOS coding in that DOS programs actively try and get input form the user, by functions such as gets(), getch(), etc... When a windows program responds to a message this is called handling the message and can be as simple as returning zero, or as involved as anything you can imagine.

Due to the message-handling functionality of windows it is rare that you will ever call a function to get input from the user. Nearly everything that needs doing can be done by handling the appropriate message and using the information it provides.

When a message is sent to out window, it calls our windows procedure and by checking the value of the Message parameter we can see which message it was. The wParam and lParam parameters are used differently by each message to provide additional information relating to the message.

For now, since our program doesn't do anything, all we need to handle are WM_CLOSE and WM_DESTROY to allow our program to be closed. Otherwise clicking on the [x] button on the window would have no effect and the user would need to hit Ctrl+Alt+Del to terminate the program.

When the user tries to close our window we get a WM_CLOSE message. We can do anything we want to here, but unless you want to really confuse people it is best to stick to standard behaviour. This means either terminating the program right away or poping up a message box to ask the user if they want to save their work first (if saving applies to the program).

I usually take two step to closing my program, one is in WM_CLOSE to do things like prompt the user to save, and once that is done call DestroyWindow() which sends a WM_DESTRORY to our main window and then removes it from the system. WM_DESTROY is where I do thing like free resources, close files, etc... and then PostQuitMessage(). After calling PostQuitMessage you will receive no more messages and your program will terminate with the value passed to the call. PostQuitMessage() is essentially the last thing you do in your program.

Now if we had to handle all of the messages necessary to run a usefull window that would be a monumental, not to mention redundant, task indeed. Instead there is a DefWindowProc to which we can pass any message we don't want or need to handle. This simplifies things considerably by providing default behaviour and reponses to many of windows' hoard of messages.

Next we see in WinMain that we register our window class. We fill out the members of a WNDCLASSEX structure and call RegisterClassEx(). The members of the struct affect the window class as follows:

cbSize

The size of the structure.

style

Class Styles(CS_*), not to be confused with Window Styles (WS_*) This can usually be set to NULL.

lpfnWndProc

Pointer to the window procedure for this window class.

cbClsExtra

Amount of extra data allocated for this class in memory. Usually NULL.

cbWndExtra

Amount of extra data allocated in memory PER WINDOW or this type. Usually NULL.

hInstance

Handle to application instance (that we got in WinMain).

hIcon

Icon shown when the user presses Alt+Tab.

hCursor

Cursor that will be displayed over our window.

hbrBackground

Background brush to set the color of our window.

lpszMenuName

Name of a menu resource to use for the windows with this class.

lpszClassName

Name to identify the class with.

hIconSm

Small (16x16) icon to show in the taskbar and in the top left corner of the window.

We then call RegisterClassEx() and check for failure, if it fails we pop up a message which says so and abort the program by returning from the WinMain() function.

Once the class is registered, we can create a window with it. You should look up the paramters for CreateWindowEx, but I'll explain them breifly here.

The first parameter (WS_EX_CLIENTEDGE) is the extended windows style, in this case I have set it to give it a sunken inner border around the window. Set it to NULL if you'd like to see the difference. Also play with other values to see what they do.

Next (g_szClassName) we have the class name, this is a string which must match the one we used to register our class. After that we specify our Window name which is the name that will be displayed in the caption, or title bar on out window.

The parameter we have as WS_OVERLAPPEDWINDOW is the window style parameter. There are quite a few of these and you should look them up and experiment to find out what they do. These will be covered more later.

The next four parameters (CW_USEDEFAULT, CW_USEDEFAULT, 320, 240) are the X and Y co-ordinates for the top left corner of your window, and the width and height. I've set the X and Y values to CW_USEDEFAULT to let windows choose where on the screen to put the window. Remeber that the left of the screen is an X value of 0 and it increases to the right; The top of the screen is a Y value of zero which increases towards the bottom. The units are pixels, which is the smallest unit a screen can display at a given resolution.

Next (NULL, NULL, g_hInst, NULL) we have the parent window handle, the menu handle, the application instance handle, and a pointer to window creation data. The parent handle is NULL because we have no parent, this is our main(top-level) window. The menu is NULL for now since we don't have one yet. The instance handle is set to the global value we stored, and the creation data (which I almost never use) that can be used to send additional data to the window that is being created is also NULL.

Just what is NULL you ask? Well it is simply 0 (zero). I use NULL to denote a lack of value, for parameter I am not specifying, etc... whereas I use 0 to say I am specifying an actual valid value of 0. They are completely the same except for appearences. For example I would pass NULL to a function that should ignore the parameter, and I would pass 0 to a function for which an integer value (lets say, a co-ordinate) of zero is completely valid.

   ShowWindow(hwnd, nCmdShow);
   UpdateWindow(hwnd);

   while(GetMessage(&Msg, NULL, 0, 0))
   {
      TranslateMessage(&Msg);
      DispatchMessage(&Msg);
   }
   return Msg.wParam;

This is the Big Moment!!! We now enter the [drumroll please] Message Loop!

ta daa.

This loop runs the whole show. GetMessage gets a message from your applications message queue, TranslateMessage does some additional processing on keyboard events like generating WM_CHAR messages to go along with WM_KEYDOWN messages. Finally DispatchMessage sends the message to our (or another) window procedure.

When you finally call PostQuitMessage() at the end of your program, the GetMessage functions returns 0 and the while loop terminates and we exit the program and return the value from the PostQuitMessage call which is contained in Msg.wParam.

Phew. Well that's it! If I haven't explained stuff clearly enough yet, just hang in there and hopefully things will become more clear as we get into more usefull programs.

1.4. We look for things... Things that make us go.

Download window_click.zip

In the next section I am going to show you how to modify what you already have to do somehting new. This way I can just tell you "Handle this message, and do this in it..." and you will know what I mean and be able to do so without seeing an entire example.

Okay for starters take the example code for the window above and make sure it compiles and runs as expected. Then you can either keep working on it for the next little bit or copy it to a new project to modify.

We're going to add the capability to show the user what the name of our program is when they click on our window. Not very exciting, it's basically to get the hang of handling messages. Lets look at what we have in our WndProc:

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   switch(Message)
   {
      case WM_CLOSE:
         DestroyWindow(hwnd);
      break;
      case WM_DESTROY:
         PostQuitMessage(0);
      break;
      default:
         return DefWindowProc(hwnd, Message, wParam, lParam);
   }
   return 0;
}

If I or someone else refers to handling a message they mean to add it into your WinMain as follows.

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   switch(Message)
   {
      case WM_LBUTTONDOWN:    // <-
                              // <-     we added this stuff
      break;                  // <-
      case WM_CLOSE:
         DestroyWindow(hwnd);
      break;
      case WM_DESTROY:
         PostQuitMessage(0);
      break;
      default:
         return DefWindowProc(hwnd, Message, wParam, lParam);
   }
   return 0;
}

First I will present the code we want to add (that will show the user the filename of our program) and then I will integrate it into our program. Later on I will probably just show you the code and let you integrate it into your program. This is of course better for me as I don't have to type as much and it's better for you because you will be able to add the code into ANY program and not just the ones I present.

char szFileName[MAX_PATH];

GetModuleFileName(hInstance, szFileName, MAX_PATH);
MessageBox(hWindow, szFileName, "This program is:", MB_OK | MB_ICONINFORMATION);

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   char szFileName[MAX_PATH]; //<- 1

   switch(Message)
   {
      case WM_LBUTTONDOWN:
         GetModuleFileName(g_hInst, szFileName, MAX_PATH);      // <- 2
         MessageBox(hwnd, szFileName, "This program is:",         // <- 3
            MB_OK | MB_ICONINFORMATION);
      break;
      case WM_CLOSE:
         DestroyWindow(hwnd);
      break;
      case WM_DESTROY:
         PostQuitMessage(0);
      break;
      default:
         return DefWindowProc(hwnd, Message, wParam, lParam);
   }
   return 0;
}

Next look at the GetModuleFileName function. Notice the first parameter has changed to match the global variable we have already declared? A lot of the time code will simply substitute a made-up variable name in order to show what value you should put there. We have no hInstance variable, but we know to use our corresponding variable g_hInst.

Finally look at the MessageBox function. You'll see we've replaced hWindow, with hwnd, which is the local variable passed into the function as paramter number one that represents our window.

Now most of the time I will try to keep my own code consistent and you shouldn't need to make some of these changes, but you need to know how.

So if you've added in that code, compile it now. If it works, click on the window and you should see a box with the name of the .exe pop up.

If it doesn't work, here's the full code to the program. Compare it to what you have and see what, if any, mistakes you made.

#include <windows.h>

static char g_szClassName[] = "MyWindowClass";
static HINSTANCE g_hInst = NULL;

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   char szFileName[MAX_PATH];

   switch(Message)
   {
      case WM_LBUTTONDOWN:
         GetModuleFileName(g_hInst, szFileName, MAX_PATH);
         MessageBox(hwnd, szFileName, "This program is:",
            MB_OK | MB_ICONINFORMATION);
      break;
      case WM_CLOSE:
         DestroyWindow(hwnd);
      break;
      case WM_DESTROY:
         PostQuitMessage(0);
      break;
      default:
         return DefWindowProc(hwnd, Message, wParam, lParam);
   }
   return 0;
}


int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
   LPSTR lpCmdLine, int nCmdShow)
{
   WNDCLASSEX WndClass;
   HWND hwnd;
   MSG Msg;

   g_hInst = hInstance;

   WndClass.cbSize        = sizeof(WNDCLASSEX);
   WndClass.style         = NULL;
   WndClass.lpfnWndProc   = WndProc;
   WndClass.cbClsExtra    = 0;
   WndClass.cbWndExtra    = 0;
   WndClass.hInstance     = g_hInst;
   WndClass.hIcon         = LoadIcon(NULL, IDI_APPLICATION);
   WndClass.hCursor       = LoadCursor(NULL, IDC_ARROW);
   WndClass.hbrBackground = (HBRUSH)(COLOR_WINDOW+1);
   WndClass.lpszMenuName  = NULL;
   WndClass.lpszClassName = g_szClassName;
   WndClass.hIconSm       = LoadIcon(NULL, IDI_APPLICATION);

   if(!RegisterClassEx(&WndClass))
   {
      MessageBox(0, "Window Registration Failed!", "Error!",
         MB_ICONEXCLAMATION | MB_OK | MB_SYSTEMMODAL);
      return 0;
   }

   hwnd = CreateWindowEx(
      WS_EX_CLIENTEDGE,
      g_szClassName,
      "The title of my window",
      WS_OVERLAPPEDWINDOW,
      CW_USEDEFAULT, CW_USEDEFAULT, 320, 240,
      NULL, NULL, g_hInst, NULL);

   if(hwnd == NULL)
   {
      MessageBox(0, "Window Creation Failed!", "Error!",
         MB_ICONEXCLAMATION | MB_OK | MB_SYSTEMMODAL);
      return 0;
   }

   ShowWindow(hwnd, nCmdShow);
   UpdateWindow(hwnd);

   while(GetMessage(&Msg, NULL, 0, 0))
   {
      TranslateMessage(&Msg);
      DispatchMessage(&Msg);
   }
   return Msg.wParam;
}

1.5. Being resourceful.

Resources are pre-defined bits of data stored in binary format inside your executable file. You create resources in a resources script, a file with an extension of ".rc". comercial compilers will have a visual resource editor which allows you to create resources without manually editing this file but sometimes editing it is the only way to go, especially if your compiler has no visual editor (or it sucks). Conversly MS (as mentioned in the rant) makes it nearly impossible to NOT use the resource editor. Unless you know what you might have a lot of trouble trying to manually edit the .rc or .rh/.h file. You will need to use the visual resource editor. I appologize on MS's behalf.

Unfortunately different compiler suites handle resources differently. I will present the way I will be showing them and then point some things out that you might have trouble with.

NOTE TO USERS OF MSVC++: A little while after begining this tutorial I aquired a copy of VC++. I can now verify that, yes in fact my examples will build in VC++. You simple create an empty Win32 workspace and add the files to it. My resources WILL work, but you will need to #include <windows.h> at the beginning of them. If you try and edit the .rc files in the visual resource editor it will probably still work BUT it will create a new file called "resource.h" which you will need to include instead of my "whatever.rh". It will also alter the .rc file considerably. I personally take great offence at software which makes unauthorised changes to my data, I will continue to use BC++ in writing this document.

First lets take a very simple resource file, with a single icon.

MYICON ICON "my_icon.ico"

#include "tut0.rh"

MYICON ICON "my_icon.ico"

MYMENU MENU
BEGIN
   POPUP "&File"
   BEGIN
      MENUITEM "E&xit", CM_FILE_EXIT
   END
END

You will see I added an #include at the top. This file will contain the ID's used for any menus or controls in the .rc file, CM_FILE_EXIT is such an ID. The .rh for each .rc you make must be included in each .c or .cpp file in which you want to use your resource ID's.

#define CM_FILE_EXIT 9001

Another point to note, some compilers may require you to #include <windows.h> in your .rc file in order to compile properly. Mine does not.

Now an example of how to use a resource in your program.

   HICON hMyIcon = LoadIcon(g_hInst, "MYICON");

Now there is an alternative way of doing things which give resources ID's instead of string names. I will show you the .rc and .rh files again but this time using ID's instead of names.

The .rh:

#define CM_FILE_EXIT 9001
#define IDI_MYICON 101
#define IDM_MYMENU 102

#include "tut0.rh"

IDI_MYICON ICON "my_icon.ico"

IDM_MYMENU MENU
BEGIN
   POPUP "&File"
   BEGIN
      MENUITEM "E&xit", CM_FILE_EXIT
   END
   END
END

   HICON hMyIcon = LoadIcon(g_hInst, MAKEINTRESOURCE(IDI_MYICON));

Usually I will use names where possible, I find them less of a hassle. If however you choose to use ID's then go ahead, you simply need to make the few small changes mentioned here.

1.6. Message, Message, Message, Message...

Understanding the message loop and entire message sending structure of windows programs is essential in order to write anything but the most trivial programs. I figured I'd better go over messages a little more here as I sort of just threw them in earlier and expected you to get it.

What is a Message?

#define WM_INITDIALOG                   0x0110
#define WM_COMMAND                      0x0111

#define WM_LBUTTONDOWN                  0x0201

Each windows message may have up to two parameters, wParam and lParam. Originally wParam was 16 bit and lParam was 32 bit, but in Win32 they are both 32 bit. Not every message uses these parameters, and each message uses them differently. For example the WM_CLOSE message doesn't use either, and you should ignore them both. The WM_COMMAND message uses both, wParam contains two values, HIWORD(wParam) is the notification message (if applicable) and LOWORD(wParam) is the control or menu id that sent the message. lParam is the HWND (Window Handle) to the control which sent the message or NULL if the messages isn't form a control.

To send a message you can use PostMessage or SendMessage. PostMessage puts the message into the Message Queue and returns immediatly. That means once the call to PostMessage is done the message may or may not have been processed yet. SendMessage sends the message directly to the window and doesn't return untill the window has finished processing it. If we wanted to close a window we could send it a WM_CLOSE message like this PostMessage(hwnd, WM_CLOSE, (WPARAM)NULL, (LPARAM)NULL); which would have the same effect as clicking on the [x] button on the top of the window. Notice that wParam and lParam are both NULL. This is because, as mentioned, they aren't used for WM_CLOSE.

What is the Message Queue

Lets say you were busy handling the WM_PAINT message and suddenly the user types a bunch of stuff on the keyboard. What should happen? Should you be interrupted in your drawing to handle the keys or should the keys just be discarded? Wrong! Obviously neither of these options is reasonable, so we have the message queue, when messages are posted they are added to the message queue and when you handle them they are removed. This ensure that you aren't going to miss messages, if you are handling one, the others will be queued up untill you get to them.

What is a Message Loop

   while(GetMessage(&Msg, NULL, 0, 0))
   {
      TranslateMessage(&Msg);
      DispatchMessage(&Msg);
   }

I hope that helps, I probably haven't explained it as well as it needs to be explained but, oh well. To really get this stuff you just have to use it a lot.

1.7. Your menu sir...

Download menu_one.zip
Download menu_two.zip

For this example you can start with the window code from above ad add this code into it as instructed.

First the .rh file. You can call it whatever you want, mine is "tut0.rh".

#define CM_FILE_EXIT 9001
#define CM_STUFF_GO 9002

#include <tut0.rh>

MYMENU MENU
BEGIN
   POPUP "&File"
   BEGIN
      MENUITEM "E&xit", CM_FILE_EXIT
   END
   POPUP "&Stuff"
   BEGIN
      MENUITEM "&Go", CM_STUFF_GO
      MENUITEM "G&o somewhere else", 0, GRAYED
   END
END

You also want to #include <tut0.rh> in your source file (.c) so that the menu command identifiers will be defined.

The easiest way to attach the menu to your window is to specify it when you register the window class, like this:

   WndClass.lpszMenuName  = "MYMENU";

An alternative to using a menu resource is to create one on the fly(or when your program runs). This is a bit more work programming wise, but adds flexibility and is sometimes necessary.

Start again from our windows program above without the .rh or .rc added. Now we will handle the WM_CREATE message and add a menu to our window.

#define CM_FILE_EXIT 9001
#define CM_STUFF_GO 9002

HMENU hMenu, hSubMenu;

hMenu = CreateMenu();

hSubMenu = CreatePopupMenu();
AppendMenu(hSubMenu, MF_STRING, CM_FILE_EXIT, "E&xit");
AppendMenu(hMenu, MF_STRING | MF_POPUP, (UINT)hSubMenu, "&File");

hSubMenu = CreatePopupMenu();
AppendMenu(hSubMenu, MF_STRING, CM_STUFF_GO, "&Go");
AppendMenu(hMenu, MF_STRING | MF_POPUP, (UINT)hSubMenu, "&Stuff");

SetMenu(hwnd, hMenu);

Okay now that we have our menu, we need to make it do something. This is pretty simple, all we need to do is handle the WM_COMMAND message. Also we'll need to check which command we are getting and act accordingly. Now our WndProc should look something like this.

LRESULT CALLBACK WndProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   HMENU hMenu, hSubMenu;
   char szFileName[MAX_PATH]; //<- 1

   switch(Message)
   {
      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            case CM_FILE_EXIT:

            break;
            case CM_STUFF_GO:

            break;
         }
      break;
      case WM_CREATE:
         hMenu = CreateMenu();

         hSubMenu = CreatePopupMenu();
         AppendMenu(hSubMenu, MF_STRING, CM_FILE_EXIT, "E&xit");
         AppendMenu(hMenu, MF_STRING | MF_POPUP, (UINT)hSubMenu, "&File");

         hSubMenu = CreatePopupMenu();
         AppendMenu(hSubMenu, MF_STRING, CM_STUFF_GO, "&Go");
         AppendMenu(hMenu, MF_STRING | MF_POPUP, (UINT)hSubMenu, "&Stuff");

         SetMenu(hwnd, hMenu);
      break;
      case WM_LBUTTONDOWN:
         GetModuleFileName(g_hInst, szFileName, MAX_PATH);      // <- 2
         MessageBox(hwnd, szFileName, "This program is:",         // <- 3
            MB_OK | MB_ICONINFORMATION);
      break;
      case WM_CLOSE:
         DestroyWindow(hwnd);
      break;
      case WM_DESTROY:
         PostQuitMessage(0);
      break;
      default:
         return DefWindowProc(hwnd, Message, wParam, lParam);
   }
   return 0;
}

We obviously want the Exit menu item to close the program. So in the WM_COMMAND, CM_FILE_EXIT handler you can use the following code to do just that.

PostMessage(hwnd, WM_CLOSE, 0, 0);

Your WM_COMMAND handler should now look like this:

   switch(LOWORD(wParam))
   {
      case CM_FILE_EXIT:
         PostMessage(hwnd, WM_CLOSE, 0, 0);
      break;
      case CM_STUFF_GO:

      break;
   }

1.8. Dialogs: GUI programmers best friend.

Download dlg_one.zip

Dialogs aren't limited to the standard open file ones, they can look like and do whatever you choose. The attractive point of dialogs is that they provide a quick way to arrange and create a GUI (Graphic User Interface) and even some default processing, cutting down on the amount of code you must write.

The first step is to create the dialog resource. As with any resource how you do this will depend on your compiler/IDE. Here I will show you the plain text of the dilaog in the .rc file and let you incorporate it into your project.

ABOUTDLG DIALOG 0, 0, 155, 102
STYLE DS_MODALFRAME | DS_3DLOOK | WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU
CAPTION "This is my About Box"
FONT 8, "MS Sans Serif"
{
   CONTROL "&OK", IDOK, "BUTTON", BS_DEFPUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 6, 83, 50, 14
   CONTROL "&Cancel", IDCANCEL, "BUTTON", BS_PUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 95, 83, 50, 14
   CONTROL "About This Program", -1, "button", BS_GROUPBOX | WS_CHILD | WS_VISIBLE | WS_GROUP, 5, 5, 144, 73
   CONTROL "An example program showing how to use dialog boxes.\r\n\r\nby theForger", -1, "static", SS_CENTER | WS_CHILD | WS_VISIBLE, 27, 27, 100, 50
}

The second line starts with STYLE and follows with the window styles that will be used to create the dialog. These should be explained under CreateWindow() in your help files.

The CAPTION line should be self explanitory.

The FONT line specifies the size and name of the font you wish to use for this dialog box. This might not end up exactly the same on each computer as different people will have different fonts and may have specified different font sizes. You usually don't need to worry about that though.

Now we have the list of controls to create on the dialog

   CONTROL "&OK", IDOK, "BUTTON", BS_DEFPUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 6, 83, 50, 14

This information should be purely academic, as you almost always use a resource editor to create dialogs, but knowing how to do it from text is sometimes necessary, expecially if you have no visual editor.

Two of the controls have an ID of -1, this is used to indicate we never need to access them, so they have no need of an identifier. However it doesn't hurt to give them an ID and your resource editor might do so automatically.

The "\r\n" in the text of the static control is a CR-LF pair, the way windows represents a new line.

So! Having added that to your .rc file we need to write a Dialog Procedure to process message for this box. Don't worry this is nothing new, it's practicly the same as our main Window Procedure.

BOOL CALLBACK AboutDlgProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   switch(Message)
   {
      case WM_INITDIALOG:

      return TRUE;
      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            case IDOK:
               EndDialog(hwnd, IDOK);
            return TRUE;
            case IDCANCEL:
               EndDialog(hwnd, IDCANCEL);
            return TRUE;
         }
      break;
   }
   return FALSE;
}

Secondly, you return FALSE for messages you don't preocess, and TRUE for messages you do process, UNLESS the message specifies you return something else.

Thirdy, You do not call DestroyWindow to close a dialog, you call EndDialog. The second paramter to which is the value that is returned to whatever code created the dialog.

Finally, instead of handling WM_CREATE, you handle WM_INITDIALOG to do any processing that needs to be done before the dialog appears, and then return TRUE to have the keyboard focus set to the default control.

Enough chit-chat, lets create the damn thing.

int ret;

   case CM_HELP_ABOUT:
      ret = DialogBox(g_hInst, "ABOUTDLG", hwnd, AboutDlgProc);
      if(ret == IDOK){
         MessageBox(hwnd, "Dialog exited with IDOK.", "Notice",
            MB_OK | MB_ICONINFORMATION);
      }
      else if(ret == IDCANCEL){
         MessageBox(hwnd, "Dialog exited with IDCANCEL.", "Notice",
            MB_OK | MB_ICONINFORMATION);
      }
      else if(ret == -1){
         MessageBox(hwnd, "Dialog failed!", "Error",
            MB_OK | MB_ICONINFORMATION);
      }
   break;

NOTE: this goes into your Main Window Procedure, NOT your Dialog Procedure.

Now I stored the return value from the call to DialogBox, this is just so you can observe the effects of pressing the two buttons, hitting ESC, ENTER etc... from inside the dialog. It also illustrates how to use the return value from a dialog box to check for success, failure, a users choice, or whatever other information you choose to send back to the caller from the Dialog Procedure.

DialogBox(g_hInst, "ABOUTDLG", hwnd, AboutDlgProc);

That's it! Sit IDD_UBU, sit.

1.9. Old dialog, new tricks.

First thing. DialogBox create the dialog and then does not return until the dialog calls EndDialog for whatever reason. If you want the dialog to be created and then hang around while your code goes on to do other things, and allows the user to interact with the rest of your program, you want to use CreateDialog in place of DialogBox. CreateDialog return a handle to the new window immediately. You can use DestroyWindow() to kill it when it is no longer needed.

Second, dialogs usually contain fancier control than just buttons, like listboxes, comboboxes, edit controls, check boxes, and even the newer Common Controls: rich edit, ListView, TreeView etc...

These controls will probably be covered later but for now here are a few usefull functions to help you explore on your own.

GetDlgItem()

This retreives the handle to a control on a dialog box. It can also be used on any parent-child window combination where the child has a unique ID.

Set/GetDlgItemText()

Self explainetory. Sets or gets the text from a control.

Set/GetDlgItemInt()

Like the above but converts to/from an int in the process (very handy).

IsDlgItemChecked()/CheckDlgItem()

Get or Set the checked state of a radio or check box.

CheckRadioButton()

Check one radio button in a group and unset the rest.

Also look up DialogBoxParam(), and CreateDialogParam(), for an easy way to pass information to a dialog you are creating.

A few notes on Dialog behaviour. Hitting the TAB key moves through the controls in the order they were created as long as they have the WS_TABSTOP style set. Hitting the Enter key while the keyboard focus is NOT on a button will activate the default button if one is set. The default default button is IDOK. Hitting ESC sends an IDCANCEL, and clicking the [x] button also sends an IDCANCEL by default.

1.10. Being in Control of the situation.

Without controls, GUI programming would be a pain in the ass for sure (even more than it already is). Buttons, Edit Boxes, Check Boxes, Sliders, Static Text, are all controls. Now controls are windows, just like any of our windows that we create, except they have pre-defined window classes and window procedures for handling them, their behaviour and appearance.

We've already done buttons in our last dialog example, so now I'll do a few real-quick examples of how to use some of the other controls. These will be completely useless but will demonstrate their use so you can add them in to other projects, and so I won't need to explain them in further examples.

Edit

Download edit_single.zip

The .rh

#define IDC_EDITDLG_TEXT      101
#define IDC_EDITDLG_SETTEXT   102

#include "edit_single.rh"

EDITDLG DIALOG 0, 0, 149, 49
STYLE DS_MODALFRAME | DS_3DLOOK | DS_CENTER | 0x200L | WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU
CAPTION "A Window"
FONT 8, "MS Sans Serif"
{
 CONTROL "", IDC_EDITDLG_TEXT, "edit", ES_LEFT | ES_AUTOHSCROLL | WS_CHILD | WS_VISIBLE | WS_BORDER | WS_TABSTOP, 3, 8, 139, 12
 CONTROL "&Set Text", IDC_EDITDLG_SETTEXT, "button", BS_DEFPUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 6, 28, 50, 14
 CONTROL "&Close", IDCANCEL, "BUTTON", BS_PUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 92, 28, 50, 14
}

#include <windows.h>
#include "edit_single.rh"

#define BUFFER_SIZE 256

BOOL CALLBACK EditDlgProc(HWND hwnd,UINT Message, WPARAM wParam, LPARAM lParam)
{
   char szText[BUFFER_SIZE];

   switch(Message)
   {
      case WM_INITDIALOG:
         SendDlgItemMessage(hwnd, IDC_EDITDLG_TEXT, EM_SETLIMITTEXT,
            (WPARAM)BUFFER_SIZE - 1, (LPARAM)0);
      return TRUE;
      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            case IDC_EDITDLG_SETTEXT:
               GetDlgItemText(hwnd, IDC_EDITDLG_TEXT, szText, BUFFER_SIZE);
               SetWindowText(hwnd, szText);
            return TRUE;
            case IDCANCEL:
               EndDialog(hwnd, IDCANCEL);
            return TRUE;
         }
      break;
   }
   return FALSE;
}


int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
   LPSTR lpCmdLine, int nCmdShow)
{
   DialogBox(hInstance, "EDITDLG", 0, EditDlgProc);
   return 0;
}

We've made the "Set Text" button the default so that hittng Enter while in the edit control will trigger it. You can also trigger it by hitting Alt+S because that is the underlined letter (see the "&" in the control text). If you want the enter to actually go into the edit box and create a new line then you need to set the ES_WANTRETURN and ES_MULTILINE styles.

That's the last call to DialogBox I'll show unless necessary, you should be able to figure it out on your own from now on. Also I'll expect you to be able to handle writing your own .rh files.

Check Box

Download check_one.zip

The Dialog resource.

CHECKDLG DIALOG 0, 0, 152, 46
STYLE DS_MODALFRAME | DS_3DLOOK | DS_CENTER | 0x200L | WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU
CAPTION "A Window"
FONT 8, "MS Sans Serif"
{
 CONTROL "This &here is a check box.", IDC_CHECKDLG_ACHECK, "button", BS_AUTOCHECKBOX | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 7, 8, 107, 12
 CONTROL "&Check the Check", IDC_CHECKDLG_CHECKTHECHECK, "button", BS_PUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 5, 26, 81, 14
 CONTROL "E&xit", IDCANCEL, "BUTTON", BS_PUSHBUTTON | BS_CENTER | WS_CHILD | WS_VISIBLE | WS_TABSTOP, 95, 26, 50, 14
}

BOOL CALLBACK CheckDlgProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   switch(Message)
   {
      case WM_INITDIALOG:
         CheckDlgButton(hwnd, IDC_CHECKDLG_ACHECK, BST_CHECKED);
      return TRUE;
      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            case IDC_CHECKDLG_CHECKTHECHECK:
               if(IsDlgButtonChecked(hwnd, IDC_CHECKDLG_ACHECK) == BST_CHECKED){
                  MessageBox(hwnd, "The Box is CHECKED!", "Woo.",
                     MB_OK | MB_ICONINFORMATION);
               }
               else {
                  MessageBox(hwnd, "The Box is NOT checked!", "Woo.",
                     MB_OK | MB_ICONINFORMATION);
               }
            return TRUE;
            case IDCANCEL:
               EndDialog(hwnd, IDCANCEL);
            return TRUE;
         }
      break;
   }
   return FALSE;
}

Now this check box was an BS_AUTOCHECKBOX, which mean it handles the checking/unchecking automatically. Change the BS_AUTOCHECKBOX to BS_CHECKBOX and run the program again. What happens? You can't change the check box! This is becuase it's operation is no longer automatic, we need to do it manually....

BOOL CALLBACK CheckDlgProc(HWND hwnd, UINT Message, WPARAM wParam, LPARAM lParam)
{
   switch(Message)
   {
      case WM_INITDIALOG:
         CheckDlgButton(hwnd, IDC_CHECKDLG_ACHECK, BST_CHECKED);
      return TRUE;
      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            case IDC_CHECKDLG_ACHECK:
               if(MessageBox(hwnd, "Are you sure?", "Boo!", MB_YESNO) == IDYES)
               {
                  if(IsDlgButtonChecked(hwnd, IDC_CHECKDLG_ACHECK) == BST_CHECKED)
                  {
                     CheckDlgButton(hwnd, IDC_CHECKDLG_ACHECK, BST_UNCHECKED);
                  }
                  else
                  {
                     CheckDlgButton(hwnd, IDC_CHECKDLG_ACHECK, BST_CHECKED);
                  }
               }
            break;
            case IDC_CHECKDLG_CHECKTHECHECK:
               if(IsDlgButtonChecked(hwnd, IDC_CHECKDLG_ACHECK) == BST_CHECKED){
                  MessageBox(hwnd, "The Box is CHECKED!", "Woo.",
                     MB_OK | MB_ICONINFORMATION);
               }
               else {
                  MessageBox(hwnd, "The Box is NOT checked!", "Woo.",
                     MB_OK | MB_ICONINFORMATION);
               }
            return TRUE;
            case IDCANCEL:
               EndDialog(hwnd, IDCANCEL);
            return TRUE;
         }
      break;
   }
   return FALSE;
}

Download check_two.zip

Planes, Trains and Autocheckboxes..

With that thought I leave controls for now. I will of course be using them more later but they will be in the context of more usefull programs. Besides this is meant to be a tutorial/introduction, not a reference. Once you get the hang of using a few controls, the others should be no sweat.

2. Intermediate

2.1. Introduction

2.2. Controls on the Fly

   case WM_CREATE:
      CreateWindow("EDIT", "",
         WS_CHILD | WS_VISIBLE | WS_HSCROLL | WS_VSCROLL | ES_MULTILINE |
            ES_WANTRETURN,
         CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT,
         hwnd, (HMENU)IDC_MAIN_TEXT, g_hInst, NULL);

      SendDlgItemMessage(hwnd, IDC_MAIN_TEXT, WM_SETFONT,
         (WPARAM)GetStockObject(DEFAULT_GUI_FONT), MAKELPARAM(TRUE, 0));
   break;
   case WM_SIZE:
      if(wParam != SIZE_MINIMIZED)
         MoveWindow(GetDlgItem(hwnd, IDC_MAIN_TEXT), 0, 0, LOWORD(lParam),
            HIWORD(lParam), TRUE);
   break;

I send a WM_SETFONT to the edit to set it to your default font used in dialogs. If I didn't, you'd get the default ugly system font.

In the WM_SIZE we resize the control to fit the new dimentions of our window, unless the window has been minimised, in which case there is no need.

This process is not limited to EDIT's, you can create buttons, slider, or any other kind of control this way as well.

2.3. Things we have in Common

You know that dialog box you get when you go File -> Open in almost any program? Chances are it is one of the Common Dialogs; these are pre-defined dialogs with pre-defined behaviour to do tasks that are so common that everybody would get really annoyed if they had to re-program them into every application.

It is a simple task to allow the user to choose a file for opening...

   case CM_FILE_OPEN:
   {
      OPENFILENAME ofn;
      char szFileName[MAX_PATH];

      ZeroMemory(&ofn, sizeof(ofn));
      szFileName[0] = 0;

      ofn.lStructSize = sizeof(ofn);
      ofn.hwndOwner = hwnd;
      ofn.lpstrFilter = "Text Files (*.txt)\0*.txt\0All Files (*.*)\0*.*\0\0";
      ofn.lpstrFile = szFileName;
      ofn.nMaxFile = MAX_PATH;
      ofn.Flags = OFN_EXPLORER | OFN_FILEMUSTEXIST | OFN_HIDEREADONLY;
      ofn.lpstrDefExt = "txt";

      if(GetOpenFileName(&ofn)){
         MessageBox(hwnd, szFileName, "You chose...", MB_OK);
      }
   }
   break;

Other Common Dialogs allow the user to select a color, a printer, a font and so on.

2.4. Reading and Writing Files

Since this is a Win32 API document I will cover the Win32 API functions. Chances are these calls eventually call the standard C functions at some point anyway. If you wish to use one of the other file manipulation techniques, feel free to do so.

Opening and Reading Files

Say for example you have allowed the user to select a file using GetOpenFileName()...

BOOL LoadFile(HWND hEdit, LPSTR pszFileName)
{
   HANDLE hFile;
   BOOL bSuccess = FALSE;

   hFile = CreateFile(pszFileName, GENERIC_READ, FILE_SHARE_READ, NULL,
      OPEN_EXISTING, NULL, NULL);
   if(hFile != INVALID_HANDLE_VALUE)
   {
      DWORD dwFileSize;
      dwFileSize = GetFileSize(hFile, NULL);
      if(dwFileSize != 0xFFFFFFFF)
      {
         LPSTR pszFileText;
         pszFileText = GlobalAlloc(GPTR, dwFileSize + 1);
         if(pszFileText != NULL)
         {
            DWORD dwRead;
            if(ReadFile(hFile, pszFileText, dwFileSize, &dwRead, NULL))
            {
               pszFileText[dwFileSize] = 0; // Null terminator
               if(SetWindowText(hEdit, pszFileText))
                  bSuccess = TRUE; // It worked!
            }
            GlobalFree(pszFileText);
         }
      }
      CloseHandle(hFile);
   }
   return bSuccess;
}

Note the variable dwRead, we don't use it except as a paramter in ReadFile. This parameter MUST be there, the call will fail without it.

In the call to CreateFile GENERIC_READ means we only want read access. FILE_SHARE_READ means it's okay if other programs open the file at the same time we do, but ONLY if they want to read as well, we don't want them writing to the file while we are reading it. And OPEN_EXISTING means only open the file if it already exists, don't create it, and don't overwrite it.

Creating and Writing Files

BOOL SaveFile(HWND hEdit, LPSTR pszFileName)
{
   HANDLE hFile;
   BOOL bSuccess = FALSE;

   hFile = CreateFile(pszFileName, GENERIC_WRITE, NULL, NULL,
      CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
   if(hFile != INVALID_HANDLE_VALUE)
   {
      DWORD dwTextLength;
      dwTextLength = GetWindowTextLength(hEdit);
      if(dwTextLength > 0)// No need to bother if there's no text.
      {
         LPSTR pszText;
         pszText = GlobalAlloc(GPTR, dwTextLength + 1);
         if(pszText != NULL)
         {
            if(GetWindowText(hEdit, pszText, dwTextLength + 1))
            {
               DWORD dwWritten;
               if(WriteFile(hFile, pszText, dwTextLength, &dwWritten, NULL))
                  bSuccess = TRUE;
            }
            GlobalFree(pszText);
         }
      }
      CloseHandle(hFile);
   }
   return bSuccess;
}

A Simple Text Editor

Download file_one.zip

2.5. Pretty pictures

Download image_one.zip

Basic windows graphics, using the GDI(Graphics Device Interface) revolves around Bitmaps (HBITMAP), and Device Contexts (HDC). A Bitmap is, of course, an image, DC's are a little more complex. While using GDI you don't change your images directly, you manipulate them with the GDI API calls which alter the image via a Device Context.

A Device Context is a generic handle for an imaging device, a monitor, window, printer or an in memory image. Thus you can use the same code (well, sortof) to draw to a printer as you can to draw to the screen.

In order to use images, we create a Memory DC. At first this is useless as it has nowhere to draw to, so along with the DC we create a Bitmap. We select the bitmap into the DC, and voila! We can now draw to the Memory DC, which affects the Bitmap selected into it. IMPORTANT NOTE: When you are drawing to a Memory DC you are actually drawing on the Bitmap selected into it, NOT the DC itself! Just like when you draw to a screen DC, the changes affect the screen, not the DC itself. A memory DC is the ONLY kind of DC you can select a Bitmap into.

On with the show. First you need to add a bitmap to your .rc file:

BALLBMP BITMAP "ball.bmp"

HBITMAP hbmBall;

hbmBall = LoadBitmap(g_hInst, "BALLBMP");
if(!hbmBall){
   MessageBox(hwnd, "Load of resource BALLBMP failed.", "Error",
      MB_OK | MB_ICONEXCLAMATION);
}

if(hbmBall)
{
   PAINTSTRUCT ps;
   HDC hdcMemory, hdcWindow;
   BITMAP bm;

   hdcWindow = BeginPaint(hwnd, &ps);
   hdcMemory = CreateCompatibleDC(hdcWindow);

   SelectObject(hdcMemory, hbmBall);
   GetObject(hbmBall, sizeof(bm), &bm);

   BitBlt(hdcWindow, 0, 0, bm.bmWidth, bm.bmHeight, hdcMemory, 0, 0, SRCCOPY);

   DeleteDC(hdcMemory);
   EndPaint(hwnd, &ps);
}

Next CreateCompatibleDC creates a Memory DC that is compatible with our Window DC. This DC is initially empty. We need to call SelectObject to select the Bitmap into the Memory DC. Now operations performed on the DC use and affect the Bitmap.

We use GetObject to get the bitmap info, width and height, and store it in a BITMAP struct.

BitBlt is da bomb! BitBlt copies TO the first DC (hdcWindow), FROM the second one (hdcMemory). If you switched the DCs, then you would effectively take a snapshop of the Window and store it in the Bitmap! The four parameters following the first DC are the x, y, width and height, for the Destination (where to put the image). The two parameters after the second DC are the x and y co-ordinates of the top-left of the image, (where to start copying from). The last parameter is the type of operation to perform. In this case we use SRCCOPY which means COPY the SouRCe DC (the image) to the destination DC (the window). After we're done we delete the memory DC, and release the window DC with a call to EndPaint(). When we're done with the Bitmap, we can get rid of it thusly...

DeleteObject(hbmBall);

Transparent images

Download image_two.zip

Color Image.
Mask.

By combining these images at run-time we give an effect of transparency. First off, add the mask to your resource, and load it like you did the color image. All we have to do now is change the way we draw a little bit...

if(hbmBall && hbmMask)
{
   PAINTSTRUCT ps;
   HDC hdcMemory, hdcWindow;
   BITMAP bm;

   hdcWindow = BeginPaint(hwnd, &ps);
   hdcMemory = CreateCompatibleDC(hdcWindow);

   GetObject(hbmBall, sizeof(bm), &bm);

   SelectObject(hdcMemory, hbmMask);
   BitBlt(hdcWindow, 0, 0, bm.bmWidth, bm.bmHeight, hdcMemory, 0, 0, SRCAND);

   SelectObject(hdcMemory, hbmBall);
   BitBlt(hdcWindow, 0, 0, bm.bmWidth, bm.bmHeight, hdcMemory, 0, 0, SRCPAINT);

   DeleteDC(hdcMemory);
   EndPaint(hwnd, &ps);
}

Next we select the color image into the Memory DC, this replaces the mask image, which becomes de-selected. We copy this to the Window DC with the SRCPAINT parameter. This does a bitwise OR operation to combine the source and destination. This has the effect of coloring in the blackened part, and also leaves the transparent part untouched.

Why did we bother with the mask then, if the second call is appearently transparent all on it's own? Well because the second call only works if the image beneath it is black, this is why we need to black it out with the mask first. (To fully understand this, you need to understand bitwise operations, OR and AND).

Only read this paragraph if you care about doing things the absolute right way. When calling SelectObject, the previous object of the same type that you are selecting gets de-selected. So if I select a bitmap into the DC, the previous bitmap gets de-selected. Now when you create a DC, there are certain objects created by default, pens, brushes, fonts, etc... and so when you select in a new one, you need to store the return value (which is the old object) and put it back when you are done. If you don't, these dead objects build up in memory and waste resources, a Very Bad Thiing. HOWEVER the documentation I have seen says is that there is NO default Bitmap. And thus we don't need to worry about storing and replacing it (although you can if you want to). This is a subject of much debate, as nobody seems to know for sure. MS's documents sometimes seem to contradict themselves, and in MS's examples they don't worry about replaceing this default object. GDI is general seems to be a large grey area where nobody really knows what is going on. And so my final point: This is the way I do it, and it works. But if I turn out to be wrong, don't blame me for providing false information. It is true to the best of my knowledge.

2.6. It LIIIIIIVVVESS!!!

Download anim_one.zip

For simplistic animation (which is the only kind I'm going to cover, sorry) you can use the low-resolution windows timer. SetTimer() sets a timer and either calls a function of your choosing, or posts a WM_TIMER to your window. We'll go the WM_TIMER method.

   const UINT idTimer1 = 1;
   UINT nTimerDelay = 100;

   SetTimer(hwnd, idTimer1, 100, NULL);

   case WM_TIMER:
      if(hbmBall && hbmMask)
      {
         HDC hdcWindow;
         hdcWindow = GetDC(hwnd);

         EraseBall(hdcWindow);
         UpdateBall(hwnd);
         DrawBall(hdcWindow);

         ReleaseDC(hwnd, hdcWindow);
      }
   break;

As you can see I've seperated the actual functionality of this message into three custom functions which I wrote to accomplish the task of erasing the old image, calculating the position of the new one and then finally drawing the new one.

void EraseBall(HDC hdc)
{
   RECT rc;
   rc.left = ballX;
   rc.top = ballY;
   rc.right = ballX + bm.bmWidth;
   rc.bottom = ballY + bm.bmHeight;
   FillRect(hdc, &rc, (HBRUSH)(COLOR_BTNFACE+1));
}

void UpdateBall(HWND hwnd)
{
   RECT rc;
   GetClientRect(hwnd, &rc);

   ballX += deltaX;
   ballY += deltaY;

   if(ballX < 0){
      ballX = 0;
      deltaX = deltaValue;
   }
   else if(ballX + bm.bmWidth > rc.right){
      ballX = rc.right - bm.bmWidth;
      deltaX = -deltaValue;
   }
   if(ballY < 0){
      ballY = 0;
      deltaY = deltaValue;
   }
   else if(ballY + bm.bmHeight > rc.bottom){
      ballY = rc.bottom - bm.bmHeight;
      deltaY = -deltaValue;
   }
}

void DrawBall(HDC hdc)
{
   HDC hdcMemory;
   hdcMemory = CreateCompatibleDC(hdc);

   SelectObject(hdcMemory, hbmMask);
   BitBlt(hdc, ballX, ballY, bm.bmWidth, bm.bmHeight, hdcMemory, 0, 0, SRCAND);

   SelectObject(hdcMemory, hbmBall);
   BitBlt(hdc, ballX, ballY, bm.bmWidth, bm.bmHeight, hdcMemory, 0, 0, SRCPAINT);

   DeleteDC(hdcMemory);
}

A few notes about UpdateBall; I've said this already but just to be clear... In windows (usually) the co-ordinate structure is such that the left side of something has an X value of 0 and X increases to the right. The top of a window or the screen (depending) has a Y value of 0 and it increases downwards. GetClientRect fills a RECT with the co-ordinates of the windows client area. The left and top values are ALWAYS zero. The right and bottom values are the width and height of the client area respectively. The client area again is the blank part of the window that is NOT the menu, title, frame etc...

When we're all done, we get rid of our timer (there are only so many to go around).

   KillTimer(hwnd, idTimer1);

Double Buffering

Download anim_two.zip

One way of alleviating this problem is to use double buffering. This is essentially doing all your drawing and updates off screen, and then Blt'ing them to the screen in a single motion. This is especially handy when multiple objects are being drawn.

Since we are allocating a buffer in memory we want to me more picky about the size of your window. We make it a fixed size and declare a few constants for the width and height of our animation area (see example code).

   hdcBuffer = CreateCompatibleDC(0);
   SelectObject(hdcBuffer, hbmBall);
   hbmBuffer = CreateCompatibleBitmap(hdcBuffer, ANIM_WIDTH, ANIM_HEIGHT);
   SelectObject(hdcBuffer, hbmBuffer);
   if(!hbmBuffer){
      MessageBox(hwnd, "Buffer creation failed.", "Error",
         MB_OK | MB_ICONEXCLAMATION);
      return -1;
   }

   if(hbmBall && hbmMask)
   {
      HDC hdcWindow;
      hdcWindow = GetDC(hwnd);

      EraseBall(hdcBuffer);
      UpdateBall();
      DrawBall(hdcBuffer);

      BitBlt(hdcWindow, 0, 0, ANIM_WIDTH, ANIM_HEIGHT, hdcBuffer, 0, 0, SRCCOPY);

      ReleaseDC(hwnd, hdcWindow);
   }

That's pretty much it for explaining, the code has a few more changes but they are not major nor essentially double-buffer related.

2.7. MDI: Please sir, can I have some more?

Download mdi_one.zip
Diagram mdi_diagram.gif

First a bit of background... Every window has a Client Area, this is where most programs draw images, place controls etc... the Client Area is not seperate from the window itself, it is simply a smaller specialised region of it. Sometimes a window can be all client area, and nothing else, sometimes the client area is smaller to make room for menus, titles, scrollbars, etc...

In MDI terms, your main window is called the Frame, this is probably the only window you would have in a SDI (Single Document Interface) program. In MDI there is an additional window, called the MDI Client Window which is a child of your Frame window. Unlike the Client Area it is a complete and seperate window all on it's own, it has a client area of it's own and probably a few pixels for a border. You never directly handle messages for the MDI Client, it is done by the pre-defined windows class "mdiclient". You can communicate and manipulate the MDI Client and the windows it contains through messages.

When it comes to the windows which actually display your document or whatever, you send a message to the MDI Client to tell it to create a new window of the type you've specified. The new window is created as a child of the MDI Client, not of your Frame window. This new window is an MDI Child. The MDI Child is a child of the MDI Client, which in turn is a child of the MDI Frame (Getting dizzy yet?). To make matters worse, the MDI Child will probably have child windows of its own, for instance the edit control in the example program for this section.

You are responsable for writing two (or more) Window Procedures. One, just like always, for your main window(the Frame). And one more for the MDI Child. You may also have more than one type of Child, in which case, you'll want a seperate window procedure for each type.

Doing MDI requires several changes and additions throughout your program. First of all, we need to register an extra window class for our child windows.

   WNDCLASSEX WndClassEx;

   WndClassEx.cbSize          = sizeof(WNDCLASSEX);
   WndClassEx.style           = CS_HREDRAW | CS_VREDRAW;
   WndClassEx.lpfnWndProc     = WndProc;
   WndClassEx.cbClsExtra      = 0;
   WndClassEx.cbWndExtra      = 0;
   WndClassEx.hInstance       = hInstance;
   WndClassEx.hIcon           = LoadIcon(NULL, IDI_APPLICATION);
   WndClassEx.hCursor         = LoadCursor(NULL, IDC_ARROW);
   WndClassEx.hbrBackground   = (HBRUSH)(COLOR_3DSHADOW+1);
   WndClassEx.lpszMenuName	   = "MAIN";
   WndClassEx.lpszClassName   = g_szAppName;
   WndClassEx.hIconSm		   = LoadIcon(NULL, IDI_APPLICATION);

   if(!RegisterClassEx(&WndClassEx))
   {
      MessageBox(0, "Could Not Register Window", "Oh Oh...",
         MB_ICONEXCLAMATION | MB_OK);
      return -1;
   }

   WndClassEx.lpfnWndProc     = MDIChildWndProc;
   WndClassEx.lpszMenuName	   = NULL;
   WndClassEx.lpszClassName   = g_szChild;
   WndClassEx.hbrBackground   = (HBRUSH)(COLOR_3DFACE+1);

   if(!RegisterClassEx(&WndClassEx))
   {
      MessageBox(0, "Could Not Register Child Window", "Oh Oh...",
         MB_ICONEXCLAMATION | MB_OK);
      return -1;
   }

We also need to modify our message loop a little...

   while(GetMessage(&Msg, NULL, 0, 0))
   {
      if (!TranslateMDISysAccel(g_hMDIClient, &Msg))
      {
         TranslateMessage(&Msg);
         DispatchMessage(&Msg);
      }
   }

Once our Frame is created just like normal, we want to also create the MDI Client, so in our Frame window's WM_CREATE handler we do...

   CLIENTCREATESTRUCT ccs;

   // Find window menu where children will be listed
   ccs.hWindowMenu  = GetSubMenu(GetMenu(hwnd), 2);
   ccs.idFirstChild = ID_MDI_FIRSTCHILD;

   g_hMDIClient = CreateWindowEx(WS_EX_CLIENTEDGE, "mdiclient", NULL,
      WS_CHILD | WS_CLIPCHILDREN | WS_VSCROLL | WS_HSCROLL,
      CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT,
      hwnd, (HMENU)ID_MDI_CLIENT, g_hInst, (LPVOID)&ccs);

   ShowWindow(g_hMDIClient, SW_SHOW);
   return 0;

ccs.hWindowMenu specifies the menu to which the MDI Client will add a list of the Child windows too. This menu is usually called "Window". The adding and removing of the windows to the menu is handled automatically by the MDI Client. This allows the user to switch to a specified window by clicking the approriate menu item. This functionality is handled by DefFrameProc which we'll get to in a bit.

ccs.idFirstChild is a number to use as the first ID for the items the Client adds to the Window menu... you want this to be easily distinguishable from your own menu identifiers so you can handle your menu commands and pass the Window menu commands to DefWindowProc for processing. In the example I specify an identifier defined as 50000, high enough that I know none of my menu command id's will be above it.

There are a few changes that need to be made to the WM_COMMAND handler for the Frame window...

   case WM_COMMAND:
   {
      switch(LOWORD(wParam))
      {
         case CM_FILE_EXIT:
            PostMessage(hwnd, WM_CLOSE, 0, 0);
         break;
         case CM_FILE_NEW:
         {
            MDICREATESTRUCT mcs;
            HWND hChild;

            mcs.szTitle = "[Untitled]";
            mcs.szClass = g_szChild;
            mcs.hOwner  = g_hInst;
            mcs.x = mcs.cx = CW_USEDEFAULT;
            mcs.y = mcs.cy = CW_USEDEFAULT;
            mcs.style = MDIS_ALLCHILDSTYLES;

            hChild = (HWND)SendMessage(g_hMDIClient, WM_MDICREATE,
               0, (LONG)&mcs);
            if(!hChild)
            {
               MessageBox(hwnd, "MDI Child creation failed.", "Oh Oh...",
                  MB_ICONEXCLAMATION | MB_OK);
            }
         }
         break;

         // handle more commands....

         default:
         {
            if(LOWORD(wParam) >= ID_MDI_FIRSTCHILD){
               DefFrameProc(hwnd, g_hMDIClient, Message, wParam, lParam);
            }
            else {
               HWND hChild;
               hChild = (HWND)SendMessage(g_hMDIClient, WM_MDIGETACTIVE,0,0);
               if(hChild){
                  SendMessage(hChild, WM_COMMAND, wParam, lParam);
               }
            }
         }
      }
   }

In response to the File->New command we want to create a new Child window. This is done not with the usual CreateWindow() but by sending a message to the MDI Client (WM_MDICREATE) telling it to create a child with the given properties specified in the MDICREATESTRUCT. You can look up the various members of this struct in your documentation, they are fairly straight forward. The return value from the WM_MDICREATE message is the handle to the newly created window.

One member of MDICREATESTRUCT that I didn't use that can be quite usefull is the lParam member. This can be used to send a 32bit value (like a pointer) to the child you are creating, to provide it with any custom information you choose. However accessing this value from your child window can be a little tricky. In the WM_CREATE handler for your child window, the lParam value for the WM_CREATE message will point to a CREATESTRUCT. the lpCreateParams member of that structure will point to the MDICREATESTRUCT you sent along with WM_MDICREATE. So in order to access the lParam value from the Child window you need to do something like this...

   case WM_CREATE:
   {
      CREATESTRUCT* pCreateStruct;
      MDICREATESTRUCT* pMDICreateStruct;

      pCreateStruct = (CREATESTRUCT*)lParam;
      pMDICreateStruct = (MDICREATESTRUCT*)pCreateStruct->lpCreateParams;

      /*
         pMDICreateStruct now points to the same MDICREATESTRUCT that you
         sent along with the WM_MDICREATE message and you can use it
         to access the lParam.
      */
   }
   break;

I didn't use the lParam in my example to keep things simpler and instead used the title of the child window to store the filename.

Finally at the end of our Frame's window procedure we've made a change...

   default:
      return DefFrameProc(hwnd, g_hMDIClient, Message, wParam, lParam);

Now comes the second window procedure, the one for our child windows...

LRESULT CALLBACK MDIChildWndProc(HWND hwnd, UINT Message, WPARAM wParam,
   LPARAM lParam)
{
   switch(Message)
   {
      // handle normal stuff...WM_CREATE etc...

      case WM_MDIACTIVATE:
      {
         HMENU hMenu, hFileMenu;
         UINT EnableFlag;

         hMenu = GetMenu(g_hMainWindow);
         if(hwnd == (HWND)lParam){      //being activated, enable the menus
            EnableFlag = MF_ENABLED;
         }
         else{                          //being de-activated, gray the menus
            EnableFlag = MF_GRAYED;
         }
         
         EnableMenuItem(hMenu, 1, MF_BYPOSITION | EnableFlag);
         EnableMenuItem(hMenu, 2, MF_BYPOSITION | EnableFlag);

         hFileMenu = GetSubMenu(hMenu, 0);
         EnableMenuItem(hFileMenu, CM_FILE_SAVE, MF_BYCOMMAND | EnableFlag);
         EnableMenuItem(hFileMenu, CM_FILE_SAVEAS, MF_BYCOMMAND | EnableFlag);

         DrawMenuBar(g_hMainWindow);
      }
      break;
      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            //handle various commands...
         }
      return 0;
   }
   return DefMDIChildProc(hwnd, Message, wParam, lParam);
}

WM_MDIACTIVATE is sent when the user switches between child windows. It is sent to both the window being activated and the one being deactivated (both of which are specified as parameters). Menu handling in MDI is a little different than normal, since you have several windows competing for the same menu bar and each one potentially has a different set of menu-items available, or even a completely seperate menu altogether. I've chosen to use a single menu and simply have each window enable the items it uses when it is activated and disable them when it is deactivated. Now of course in the example program there is only one type of Child window, so most of the time the menu will be in only one state, but when the last window is closed (or none have been opened yet) and there is no other window to enable the menu, some of the items will remain grayed out, as they only apply when working with a child window. In a program that handles multiple document types you might choose to modify or even completely replace the menu for each child. SetMenu/GetMenu or WM_MDISETMENU can be used to accomplish this. WM_MDISETMENU can also be used to change under which submenu the MDI children are listed.

You must keep in mind when dealing with MDI children that the menu and possibly statusbar or toolbar are shared between windows. Caution must be taken to avoid one window making changes which will cause another window to function improperly.

MDI features such as Tile and Cascade may be enabled by sending a WM_MDITILE, or WM_MDICASCADE message to the MDI Client.

Please note... in the example, program termination is a little inelegant. The program simply closes and takes all the child windows with it. Ideally you would post a WM_CLOSE to each child window and allow it to query the user whether of not to close, save, or cancel etc... If you want to unconditionally detroy a child window, send WM_MDIDESTROY to the MDI Client and specify the handle of the child you wish to remove. You SHOULD NOT use DestroyWindow() to destroy an MDI Child window.

Another note about the example... I haven't discussed the file loading etc, because it is essentially the same as the text edit program example above, with a few changes to better fit the needs of MDI. I use the window title of each child to store the filename, so the child knows which file to load or save. For new files I create the child with a title of "[Untitled]" and then the child checks for the initial '[' and if it is there doesn't try to load a file.

2.8. Tool and Status Bars

A Word on Common Controls

READ THIS

As with all common controls, you must call InitCommonControls() BEFORE you try and use them. You will need to #include <commctrl.h> in order to use this function and to get the functions and declarations necessary for use of the Common Controls. You may also need to add comctl32.lib to your linker settings(do this if you get "unresolved external" errors for the Common Control functions).

Toolbars

Download toolbar_one.zip

#define ID_TOOLBAR         4998

         g_hToolBar = CreateWindowEx(0, TOOLBARCLASSNAME, NULL,
            WS_CHILD | WS_VISIBLE, 0, 0, 0, 0,
            hwnd, (HMENU)ID_TOOLBAR, g_hInst, NULL);

         // Send the TB_BUTTONSTRUCTSIZE message, which is required for
         // backward compatibility.
         SendMessage(g_hToolBar, TB_BUTTONSTRUCTSIZE, (WPARAM)sizeof(TBBUTTON), 0);

         TBADDBITMAP tbab;

         tbab.hInst = g_hInst;
         tbab.nID = IDB_TOOLBITMAP;
         SendMessage(g_hToolBar, TB_ADDBITMAP, 0, (LPARAM)&tbab);

A custom toolbar image with 4 buttons.

This only associates a bitmap with the toolbar, we still need to add the buttons and this is done with an array of TBBUTTON structs...

         TBBUTTON tbb[6];

         ZeroMemory(tbb, sizeof(tbb));
         tbb[0].iBitmap = 0;
         tbb[0].fsState = TBSTATE_ENABLED;
         tbb[0].fsStyle = TBSTYLE_BUTTON;
         tbb[0].idCommand = CM_RED_CIRCLE;

         tbb[1].fsStyle = TBSTYLE_SEP;

         tbb[2].iBitmap = 1;
         tbb[2].fsState = TBSTATE_ENABLED | TBSTATE_CHECKED;
         tbb[2].fsStyle = TBSTYLE_CHECKGROUP;
         tbb[2].idCommand = CM_GREEN_SQUARE;

         //...

iBitmap specifies the Index to the image you added with TB_ADDBITMAP.

fsState is the button state. Here we've set it to be enabled, if we wanted it to be disabled, we could leave this member as NULL.

idCommand is the command ID, this is used like the ID of a menu item or button and is the id you will check for in WM_COMMAND.

      case WM_COMMAND:
         switch(LOWORD(wParam))
         {
            case CM_RED_CIRCLE:
               MessageBox(hwnd,
                  "You clicked the Red Circle\n(as if you didn't already know)",
                  "Hi", MB_OK | MB_ICONINFORMATION);
            break;

fsStyle is the button style, TBSTYLE_BUTTON is for a normal button and TBSTYLE_CHECK is for a check button, one that toggles on/off with each click. TBSTYLE_SEP can be used to insert a seperator, and all of the other members can be NULL.

When you have set up all of the buttons in the array you send them to the toolbar...

         SendMessage(g_hToolBar, TB_ADDBUTTONS, 6, (LPARAM)&tbb);

If all goes well you should now have a nice toolbar on your window. To get it to resize when the size of your window changes (in WM_SIZE) you send a TB_AUTOSIZE message.

      case WM_SIZE:
         SendMessage(g_hToolBar, TB_AUTOSIZE, 0, 0);
      break;

To enable or disable buttons, you can use the TB_ENABLEBUTTON message...

   // Enable
   SendMessage(g_hToolBar, TB_ENABLEBUTTON, CM_RED_CIRCLE, MAKELONG(TRUE, 0));
   // Disable
   SendMessage(g_hToolBar, TB_ENABLEBUTTON, CM_RED_CIRCLE, MAKELONG(FALSE, 0));

Messages usefull for check buttons (ones that toggle on and off) are TB_CHECKBUTTON, and TB_ISBUTTONCHECKED.

There are a hundred other things you can do with toolbars but that's what the help files are for, get reading!

Standard Toolbar Buttons

Download (see mdi_two.zip below)

         tbab.hInst = HINST_COMMCTRL;
         tbab.nID = IDB_STD_SMALL_COLOR;
         SendMessage(g_hToolBar, TB_ADDBITMAP, 0, (LPARAM)&tbab);

         tbb[0].iBitmap = STD_FILENEW;
         tbb[0].fsState = TBSTATE_ENABLED;
         tbb[0].fsStyle = TBSTYLE_BUTTON;
         tbb[0].idCommand = CM_FILE_NEW;

Status Bars

Download (see mdi_two.zip below)

#define ID_STATUSBAR       4997

         g_hStatusBar = CreateWindowEx(0, STATUSCLASSNAME, NULL,
            WS_CHILD | WS_VISIBLE | SBARS_SIZEGRIP, 0, 0, 0, 0,
            hwnd, (HMENU)ID_STATUSBAR, g_hInst, NULL);

If you only want a single line of text in the status bar that's all there is to it, you can use SetWindowText() to set it. If you want to divide the bar up into smaller parts then you pass the SB_SETPARTS an array of int's specifiying the widths of each part, and the number of elements to the array. The value of each element in the array is teh number of pixels from the left side of the toolbar to the right side of the part. For example an array containing, {100, 200} would make two equal parts, one from 0 to 100 and one from 100 to 200. This is weird but that's the way it is.

         int iStatusWidths[] = {200, 300, -1};
         SendMessage(g_hStatusBar, SB_SETPARTS, 3, (LPARAM)iStatusWidths);

To set the text of the part individually you send the SB_SETTEXT message. wParam specifies the index of the part to which you want to set the text and lParam is the text itself.

         SendMessage(g_hStatusBar, SB_SETTEXT, 2,
            (LPARAM)"theForger's Toobar & Statusbar Example");

Like the toolbar the status bar will automatically adjust it's width to match the window... it does this on receipt of a WM_SIZE message.

      case WM_SIZE:
         SendMessage(g_hStatusBar, WM_SIZE, 0, 0);
      break;

Making tool and status bars behave around your (MDI) clients.

Download mdi_two.zip

      case WM_SIZE:
      {
         RECT rectClient, rectStatus, rectTool;
         UINT uToolHeight, uStatusHeight, uClientAlreaHeight;

         SendMessage(g_hToolBar, TB_AUTOSIZE, 0, 0);
         SendMessage(g_hStatusBar, WM_SIZE, 0, 0);

         GetClientRect(hwnd, &rectClient);
         GetWindowRect(g_hStatusBar, &rectStatus);
         GetWindowRect(g_hToolBar, &rectTool);

         uToolHeight = rectTool.bottom - rectTool.top;
         uStatusHeight = rectStatus.bottom - rectStatus.top;
         uClientAlreaHeight = rectClient.bottom;

         MoveWindow(g_hMDIClient, 0, uToolHeight, rectClient.right,
            uClientAlreaHeight - uStatusHeight - uToolHeight, TRUE);
      }
      break;